man: Use asciidoc for main man page as well

We already use asciidoc for the gnome-extensions man page, while
the main man page is generated from docbook XML. The former is a
much friendlier source format, so use it for both man pages.

Hopefully the plain text format encourages updates, to prevent the
page from getting as badly out of sync again as it is currently.

Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/1553>

diff --git a/man/gnome-shell.txt b/man/gnome-shell.txt
new file mode 100644 (file)
index 0000000..4ed5b71
--- /dev/null
+++ b/man/gnome-shell.txt
@@ -0,0 +1,81 @@
+GNOME-SHELL(1)
+=============
+:man manual: User Commands
+:man source: GNOME-SHELL
+:doctype: manpage
+:date: December 2020
+
+NAME
+----
+gnome-shell - Graphical shell for the GNOME desktop
+
+SYNOPSIS
+--------
+*gnome-shell* ['OPTION'...]
+
+DESCRIPTION
+-----------
+GNOME shell provides core user interface functions for the GNOME 3 desktop,
+like switching to windows and launching applications. GNOME shell takes
+advantage of the capabilities of modern graphics hardware and introduces
+innovative user interface concepts to provide a visually attractive and
+easy to use experience.
+
+gnome-shell is a required component of the GNOME desktop, i.e. it is listed in
+the RequiredComponents field of /usr/share/gnome-session/sessions/gnome.session.
+It is started in the window manager phase of the session.
+
+OPTIONS
+-------
+*-r*, *--replace*::
+Replace the running window manager
+
+*--sm-disable*::
+Disable connection to the session manager
+
+*--sm-client-id*='ID'::
+Specify session management 'ID'
+
+*--sm-save-file*='FILE'::
+Initialize session from 'FILE'
+
+*--screen*='SCREEN'::
+X screen to use
+
+*-d*, *--display*='DISPLAY'::
+X display to use
+
+*--sync*::
+Make X calls synchronous
+
+*--version*::
+Print version and exit
+
+*--help*::
+Display help and exit
+
+*--mode*='MODE'::
+Use a specific mode, e.g. "gdm" for login screen
+
+*--list-modes*::
+List possible modes and exit
+
+*--clutter-display*='DISPLAY'::
+Clutter the option display (otherwise ignored)
+
+FILES
+-----
+/usr/share/gnome-session/sessions/gnome.session,
+/usr/share/applications/org.gnome.Shell.desktop.
+
+BUGS
+----
+The bug tracker can be reached by visiting the website
+https://bugzilla.gnome.org/buglist.cgi?product=gnome-shell.
+Before sending a bug report, please verify that you have the latest version
+of gnome-shell. Many bugs (major and minor) are fixed at each release, and
+if yours is out of date, the problem may already have been solved.
+
+ADDITIONAL INFORMATION
+----------------------
+For further information, visit the website https://wiki.gnome.org/Projects/GnomeShell.

diff --git a/man/gnome-shell.xml b/man/gnome-shell.xml
deleted file mode 100644 (file)
index 2b245f7..0000000
--- a/man/gnome-shell.xml
+++ /dev/null
@@ -1,165 +0,0 @@
-<?xml version='1.0'?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-
-<refentry id="gnome-shell">
-
-        <refentryinfo>
-                <title>gnome-shell</title>
-                <productname>gnome-shell</productname>
-
-                <authorgroup>
-                        <author>
-                                <contrib>wrote the original gnome-shell man page</contrib>
-                                <firstname>Marcelo Jorge</firstname>
-                                <surname>Vieira</surname>
-                                <email>metal@alucinados.com</email>
-                        </author>
-                </authorgroup>
-
-        </refentryinfo>
-
-        <refmeta>
-                <refentrytitle>gnome-shell</refentrytitle>
-                <manvolnum>1</manvolnum>
-        </refmeta>
-
-        <refnamediv>
-                <refname>gnome-shell</refname>
-                <refpurpose>Graphical shell for the GNOME desktop</refpurpose>
-        </refnamediv>
-
-        <refsynopsisdiv>
-                <cmdsynopsis>
-                        <command>gnome-shell <arg choice="opt" rep="repeat">OPTION</arg></command>
-                </cmdsynopsis>
-        </refsynopsisdiv>
-
-        <refsect1>
-                <title>Description</title>
-
-                <para>GNOME shell provides core user
-                interface functions for the GNOME 3 desktop, like switching
-                to windows and launching applications. GNOME shell takes
-                advantage of the capabilities of modern graphics hardware
-                and introduces innovative user interface concepts to provide
-                a visually attractive and easy to use experience.</para>
-
-                <para>gnome-shell is a required component of
-                the GNOME desktop, i.e. it is listed in the
-                RequiredComponents field of
-                <filename>/usr/share/gnome-session/sessions/gnome.session</filename>.
-                It is started in the window manager phase of the session.
-                </para>
-
-        </refsect1>
-
-        <refsect1>
-                <title>Options</title>
-
-                <variablelist>
-
-                        <varlistentry>
-                                <term><option>-r</option>, <option>--replace</option></term>
-
-                                <listitem><para>Replace the running window manager</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>--sm-disable</option></term>
-
-                                <listitem><para>Disable connection to the session manager</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>--sm-client-id=<replaceable>ID</replaceable></option></term>
-
-                                <listitem><para>Specify session management <replaceable>ID</replaceable></para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>--sm-save-file=<replaceable>FILE</replaceable></option></term>
-
-                                <listitem><para>Initialize session from <replaceable>FILE</replaceable></para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>--screen=<replaceable>SCREEN</replaceable></option></term>
-
-                                <listitem><para>X screen to use</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>-d</option>, <option>--display=<replaceable>DISPLAY</replaceable></option></term>
-
-                                <listitem><para>X Display to use</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>--sync</option></term>
-
-                                <listitem><para>Make X calls synchronous</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>--version</option></term>
-
-                                <listitem><para>Print version and exit</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>--help</option></term>
-
-                                <listitem><para>Display help and exit</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>--mode=<replaceable>MODE</replaceable></option></term>
-
-                                <listitem><para>Use a specific mode, e.g. "gdm" for login screen</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>--list-modes</option></term>
-
-                                <listitem><para>List possible modes and exit</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>--clutter-display=<replaceable>DISPLAY</replaceable></option></term>
-
-                                <listitem><para>Clutter the option display (otherwise ignored)</para></listitem>
-                        </varlistentry>
-
-                </variablelist>
-
-        </refsect1>
-
-        <refsect1>
-                <title>Files</title>
-
-                <para>
-                        <filename>/usr/share/gnome-session/sessions/gnome.session</filename>,
-                        <filename>/usr/share/applications/org.gnome.Shell.desktop</filename>.</para>
-        </refsect1>
-
-        <refsect1>
-                <title>Bugs</title>
-
-                <para>The bug tracker can be reached by visiting the
-                website <ulink url="https://bugzilla.gnome.org/buglist.cgi?product=gnome-shell">https://bugzilla.gnome.org/buglist.cgi?product=gnome-shell</ulink>.
-                Before sending a bug report, please verify that you have
-                the latest version of gnome-shell. Many bugs (major and
-                minor) are fixed at each release, and if yours is out of
-                date, the problem may already have been solved.</para>
-
-        </refsect1>
-
-        <refsect1>
-                <title>Additional Information</title>
-
-                <para>For further information, visit the website
-                <ulink url="https://wiki.gnome.org/Projects/GnomeShell">https://wiki.gnome.org/Projects/GnomeShell</ulink>.</para>
-        </refsect1>
-
-</refentry>

diff --git a/man/meson.build b/man/meson.build
index 9d39a38b8c85c940f902a7ddf65355f833f0a495..aa37ef0f3a2ec3bdc433607ceaed9f533c6414e0 100644 (file)
--- a/man/meson.build
+++ b/man/meson.build
@@ -1,19 +1,7 @@
 custom_target('man page',
-  input: 'gnome-shell.xml',
+  input: ['gnome-shell.txt', 'stylesheet.xsl'],
   output: 'gnome-shell.1',
-  command: [
-    xsltproc,
-    '-o', '@OUTPUT@',
-    '--nonet',
-    '--stringparam', 'man.output.quietly', '1',
-    '--stringparam', 'funcsynopsis.style', 'ansi',
-    '--stringparam', 'man.th.extra1.suppress', '1',
-    '--stringparam', 'man.authors.section.enabled', '0',
-    '--stringparam', 'man.copyright.section.enabled', '0',
-    'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl',
-    '@INPUT@'
-  ],
-  build_by_default: true,
+  command: [a2x, '-D', '@OUTDIR@', '--xsl-file', '@INPUT1@', '-f' ,'manpage', '@INPUT0@'],
   install_dir: mandir + '/man1',
   install: true
 )

diff --git a/man/stylesheet.xsl b/man/stylesheet.xsl
new file mode 100644 (file)
index 0000000..047bd1b
--- /dev/null
+++ b/man/stylesheet.xsl
@@ -0,0 +1,27 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+               version='1.0'>
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"/>
+
+<xsl:template match="variablelist/title">
+  <xsl:text>.PP&#10;</xsl:text>
+  <xsl:call-template name="bold">
+    <xsl:with-param name="node" select="."/>
+    <xsl:with-param name="context" select=".."/>
+  </xsl:call-template>
+  <xsl:text>&#10;</xsl:text>
+</xsl:template>
+
+<xsl:template match="varlistentry[preceding-sibling::title]">
+  <xsl:if test="not(preceding-sibling::varlistentry)">
+    <xsl:text>.RS 4&#10;</xsl:text>
+    <!-- comment out the leading .PP added by the original template -->
+    <xsl:text>.\"</xsl:text>
+  </xsl:if>
+  <xsl:apply-imports/>
+  <xsl:if test="position() = last()">
+    <xsl:text>.RE&#10;</xsl:text>
+  </xsl:if>
+</xsl:template>
+
+</xsl:stylesheet>

diff --git a/meson.build b/meson.build
index c77c519269d7b4c3724328c03e7413e803dca79b..71b3ca47179408288b4268b82483c1b1712813d0 100644 (file)
--- a/meson.build
+++ b/meson.build
@@ -126,8 +126,7 @@ else
 endif
 
 if get_option('man')
-  xsltproc = find_program('xsltproc')
-
+  a2x = find_program('a2x')
   subdir('man')
 endif